home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / cat3c / xdr.z / xdr
Encoding:
Text File  |  1998-10-20  |  20.0 KB  |  595 lines
  1.  
  2.  
  3.  
  4. XXXXDDDDRRRR((((3333RRRR))))                                                                XXXXDDDDRRRR((((3333RRRR))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      xdr - External Data Representation (XDR) library routines
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS AAAANNNNDDDD DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  12.      These routines allow C programmers to describe arbitrary data structures
  13.      in a machine-independent fashion.  Data for remote procedure calls are
  14.      transmitted using these routines.
  15.  
  16.  
  17.           #include <rpc/rpc.h>
  18.  
  19.  
  20.  
  21.           bool_t
  22.           xdr_array(XDR *xdrs, caddr_t *arrp, u_int *sizep,
  23.                u_int maxsize, u_int elsize, xdrproc_t elproc)
  24.  
  25.  
  26.           A filter primitive that translates between variable-length arrays
  27.           and their corresponding external representations. The parameter _a_r_r_p
  28.           is the address of the pointer to the array, while _s_i_z_e_p is the
  29.           address of the element count of the array; this element count cannot
  30.           exceed _m_a_x_s_i_z_e.  The parameter _e_l_s_i_z_e is the _s_i_z_e_o_f each of the
  31.           array's elements, and _e_l_p_r_o_c is an XDR filter that translates
  32.           between the array elements' C form, and their external
  33.           representation.  This routine returns 1 if it succeeds, 0 otherwise.
  34.  
  35.  
  36.           bool_t
  37.           xdr_bool(XDR *xdrs, bool_t *bp)
  38.  
  39.  
  40.           A filter primitive that translates between booleans (C integers) and
  41.           their external representations. When encoding data, this filter
  42.           produces values of either 1 or 0.  This routine returns 1 if it
  43.           succeeds, 0 otherwise.
  44.  
  45.  
  46.           bool_t
  47.           xdr_bytes(XDR *xdrs, char **sp, u_int *sizep,
  48.                u_int maxsize)
  49.  
  50.  
  51.           A filter primitive that translates between counted byte strings and
  52.           their external representations.  The parameter _s_p is the address of
  53.           the string pointer. The length of the string is located at address
  54.           _s_i_z_e_p; strings cannot be longer than _m_a_x_s_i_z_e.  This routine returns
  55.           1 if it succeeds, 0 otherwise.
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. XXXXDDDDRRRR((((3333RRRR))))                                                                XXXXDDDDRRRR((((3333RRRR))))
  71.  
  72.  
  73.  
  74.           bool_t
  75.           xdr_char(XDR *xdrs, char *cp)
  76.  
  77.  
  78.           A filter primitive that translates between C characters and their
  79.           external representations.  This routine returns 1 if it succeeds, 0
  80.           otherwise.  Note: encoded characters are not packed, and occupy 4
  81.           bytes each. For arrays of characters, it is worthwhile to consider
  82.           _x_d_r__b_y_t_e_s(), _x_d_r__o_p_a_q_u_e() or _x_d_r__s_t_r_i_n_g().
  83.  
  84.  
  85.           void
  86.           xdr_destroy(XDR *xdrs)
  87.  
  88.  
  89.           A macro that invokes the destroy routine associated with the XDR
  90.           stream, _x_d_r_s.  Destruction usually involves freeing private data
  91.           structures associated with the stream.  Using _x_d_r_s after invoking
  92.           _x_d_r__d_e_s_t_r_o_y() is undefined.
  93.  
  94.  
  95.           bool_t
  96.           xdr_double(XDR *xdrs, double *dp)
  97.  
  98.  
  99.           A filter primitive that translates between C _d_o_u_b_l_e precision
  100.           numbers and their external representations.  This routine returns 1
  101.           if it succeeds, 0 otherwise.
  102.  
  103.  
  104.           bool_t
  105.           xdr_enum(XDR *xdrs, enum_t *ep)
  106.  
  107.  
  108.           A filter primitive that translates between C _e_n_u_ms (actually
  109.           integers) and their external representations.  This routine returns
  110.           1 if it succeeds, 0 otherwise.
  111.  
  112.  
  113.           bool_t
  114.           xdr_float(XDR *xdrs, float *fp)
  115.  
  116.  
  117.           A filter primitive that translates between C _f_l_o_a_ts and their
  118.           external representations.  This routine returns 1 if it succeeds, 0
  119.           otherwise.
  120.  
  121.  
  122.           void
  123.           xdr_free(xdrproc_t proc, char *objp)
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. XXXXDDDDRRRR((((3333RRRR))))                                                                XXXXDDDDRRRR((((3333RRRR))))
  137.  
  138.  
  139.  
  140.           Generic freeing routine. The first argument is the XDR routine for
  141.           the object being freed. The second argument is a pointer to the
  142.           object itself. Note: the pointer passed to this routine is _n_o_t
  143.           freed, but what it points to _i_s freed (recursively).
  144.  
  145.  
  146.           u_int
  147.           xdr_getpos(XDR *xdrs)
  148.  
  149.  
  150.           A macro that invokes the get-position routine associated with the
  151.           XDR stream, _x_d_r_s.  The routine returns an unsigned integer, which
  152.           indicates the position of the XDR byte stream.  A desirable feature
  153.           of XDR streams is that simple arithmetic works with this number,
  154.           although the XDR stream instances need not guarantee this.
  155.  
  156.  
  157.           long *
  158.           xdr_inline(XDR *xdrs, int len)
  159.  
  160.  
  161.           A macro that invokes the in-line routine associated with the XDR
  162.           stream, _x_d_r_s.  The routine returns a pointer to a contiguous piece
  163.           of the stream's buffer; _l_e_n is the byte length of the desired
  164.           buffer.  Note: the pointer is cast to _l_o_n_g *.
  165.  
  166.           Warning:  _x_d_r__i_n_l_i_n_e() may return NULL (0) if it cannot allocate a
  167.           contiguous piece of a buffer.  Therefore the behavior may vary among
  168.           stream instances; it exists for the sake of efficiency.
  169.  
  170.  
  171.           bool_t
  172.           xdr_int(XDR *xdrs, int *ip)
  173.  
  174.  
  175.           A filter primitive that translates between C integers and their
  176.           external representations.  This routine returns 1 if it succeeds, 0
  177.           otherwise.
  178.  
  179.  
  180.           bool_t
  181.           xdr_long(XDR *xdrs, long *lp)
  182.  
  183.  
  184.           A filter primitive that translates between C _l_o_n_g integers and their
  185.           external representations.  This routine returns 1 if it succeeds, 0
  186.           otherwise.
  187.  
  188.           Warning: In the IRIX 64-bit ABI, this routine may be somewhat
  189.           misleading. The external representation of a _l_o_n_g integer is defined
  190.           by the XDR standard to be a 32 bit encoding, but in the IRIX 64-bit
  191.           ABI, a _l_o_n_g integer is 64 bits. Hence, in the IRIX 64-bit ABI, _l_o_n_g
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. XXXXDDDDRRRR((((3333RRRR))))                                                                XXXXDDDDRRRR((((3333RRRR))))
  203.  
  204.  
  205.  
  206.           integers are truncated by _x_d_r__l_o_n_g(), and _x_d_r__l_o_n_g() is only useful
  207.           for encoding/decoding values in the range of -2147483648 to
  208.           2147483647.
  209.  
  210.           bool_t
  211.           xdr_longlong_t(XDR *xdrs, __int64_t *ulp)
  212.  
  213.  
  214.           A filter primitive that translates between C _6_4-_b_i_t integers and
  215.           their external representations.  This routine returns 1 if it
  216.           succeeds, 0 otherwise.
  217.  
  218.  
  219.           bool_t
  220.           xdr_opaque(XDR *xdrs, void *cp, u_int cnt)
  221.  
  222.  
  223.           A filter primitive that translates between fixed size opaque data
  224.           and its external representation.  The parameter _c_p is the address of
  225.           the opaque object, and _c_n_t is its size in bytes.  This routine
  226.           returns 1 if it succeeds, 0 otherwise.
  227.  
  228.  
  229.           bool_t
  230.           xdr_pointer(XDR *xdrs, char **objpp,
  231.                u_int objsize, xdrproc_t xdrobj)
  232.  
  233.  
  234.           Like _x_d_r__r_e_f_e_r_e_n_c_e() except that it serializes NULL pointers,
  235.           whereas _x_d_r__r_e_f_e_r_e_n_c_e() does not.  Thus, _x_d_r__p_o_i_n_t_e_r() can represent
  236.           recursive data structures, such as binary trees or linked lists.
  237.  
  238.  
  239.  
  240.           bool_t
  241.           xdr_reference(XDR *xdrs, char **pp,
  242.                u_int size, xdrproc_t proc)
  243.  
  244.  
  245.           A primitive that provides pointer chasing within structures.  The
  246.           parameter _p_p is the address of the pointer; _s_i_z_e is the _s_i_z_e_o_f the
  247.           structure that *_p_p points to; and _p_r_o_c is an XDR procedure that
  248.           filters the structure between its C form and its external
  249.           representation.  This routine returns 1 if it succeeds, 0 otherwise.
  250.  
  251.           Warning: this routine does not understand NULL pointers. Use
  252.           _x_d_r__p_o_i_n_t_e_r() instead.
  253.  
  254.  
  255.           bool_t
  256.           xdr_setpos(XDR *xdrs, u_int pos)
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. XXXXDDDDRRRR((((3333RRRR))))                                                                XXXXDDDDRRRR((((3333RRRR))))
  269.  
  270.  
  271.  
  272.           A macro that invokes the set position routine associated with the
  273.           XDR stream _x_d_r_s.  The parameter _p_o_s is a position value obtained
  274.           from _x_d_r__g_e_t_p_o_s().  This routine returns 1 if the XDR stream could
  275.           be repositioned, and 0 otherwise.
  276.  
  277.           Warning: it is difficult to reposition some types of XDR streams, so
  278.           this routine may fail with one type of stream and succeed with
  279.           another.
  280.  
  281.  
  282.           bool_t
  283.           xdr_short(XDR *xdrs, short *sp)
  284.  
  285.  
  286.           A filter primitive that translates between C _s_h_o_r_t integers and
  287.           their external representations.  This routine returns 1 if it
  288.           succeeds, 0 otherwise.
  289.  
  290.  
  291.           bool_t
  292.           xdr_string(XDR *xdrs, char **sp, u_int maxsize)
  293.  
  294.  
  295.           A filter primitive that translates between C strings and their
  296.           corresponding external representations.  Strings cannot be longer
  297.           than _m_a_x_s_i_z_e.  Note: _s_p is the address of the string's pointer.
  298.           This routine returns 1 if it succeeds, 0 otherwise.
  299.  
  300.  
  301.           bool_t
  302.           xdr_u_char(XDR *xdrs, unsigned char *cp)
  303.  
  304.  
  305.           A filter primitive that translates between _u_n_s_i_g_n_e_d C characters and
  306.           their external representations.  This routine returns 1 if it
  307.           succeeds, 0 otherwise.
  308.  
  309.  
  310.           bool_t
  311.           xdr_u_int(XDR *xdrs, unsigned *up)
  312.  
  313.  
  314.           A filter primitive that translates between C _u_n_s_i_g_n_e_d integers and
  315.           their external representations.  This routine returns 1 if it
  316.           succeeds, 0 otherwise.
  317.  
  318.  
  319.           bool_t
  320.           xdr_u_long(XDR *xdrs, unsigned long *ulp)
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.                                                                         PPPPaaaaggggeeee 5555
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334. XXXXDDDDRRRR((((3333RRRR))))                                                                XXXXDDDDRRRR((((3333RRRR))))
  335.  
  336.  
  337.  
  338.           A filter primitive that translates between C _u_n_s_i_g_n_e_d _l_o_n_g integers
  339.           and their external representations.  This routine returns 1 if it
  340.           succeeds, 0 otherwise.
  341.  
  342.           Warning: In the IRIX 64-bit ABI, this routine may be somewhat
  343.           misleading. The external representation of an _u_n_s_i_g_n_e_d _l_o_n_g integer
  344.           is defined by the XDR standard to be a 32 bit encoding, but in the
  345.           IRIX 64-bit ABI, an _u_n_s_i_g_n_e_d _l_o_n_g integer is 64 bits. Hence, in the
  346.           IRIX 64-bit ABI, _u_n_s_i_g_n_e_d _l_o_n_g integers are truncated by
  347.           _x_d_r__u__l_o_n_g(), and _x_d_r__u__l_o_n_g() is only useful for encoding/decoding
  348.           values in the range of 0 to 4294967295.
  349.  
  350.  
  351.           bool_t
  352.           xdr_u_longlong_t(XDR *xdrs, __uint64_t *ulp)
  353.  
  354.  
  355.           A filter primitive that translates between C _u_n_s_i_g_n_e_d _6_4-_b_i_t
  356.           integers and their external representations.  This routine returns 1
  357.           if it succeeds, 0 otherwise.
  358.  
  359.  
  360.           bool_t
  361.           xdr_u_short(XDR *xdrs, unsigned short *usp)
  362.  
  363.  
  364.           A filter primitive that translates between C _u_n_s_i_g_n_e_d _s_h_o_r_t integers
  365.           and their external representations.  This routine returns 1 if it
  366.           succeeds, 0 otherwise.
  367.  
  368.  
  369.           bool_t
  370.           xdr_union(XDR *xdrs, enum_t *dscmp, void *unp,
  371.                struct xdr_discrim *choices, xdrproc_t dfault)
  372.  
  373.  
  374.           A filter primitive that translates between a discriminated C _u_n_i_o_n
  375.           and its corresponding external representation. It first translates
  376.           the discriminant of the union located at _d_s_c_m_p.  This discriminant
  377.           is always an _e_n_u_m__t.  Next the union located at _u_n_p is translated.
  378.           The parameter _c_h_o_i_c_e_s is a pointer to an array of _x_d_r__d_i_s_c_r_i_m()
  379.           structures. Each structure contains an ordered pair of [_v_a_l_u_e,
  380.           _p_r_o_c].  If the union's discriminant is equal to the associated
  381.           _v_a_l_u_e, then the _p_r_o_c is called to translate the union.  The end of
  382.           the _x_d_r__d_i_s_c_r_i_m() structure array is denoted by a routine of value
  383.           NULL.  If the discriminant is not found in the _c_h_o_i_c_e_s array, then
  384.           the _d_e_f_a_u_l_t_a_r_m procedure is called (if it is not NULL).  Returns 1
  385.           if it succeeds, 0 otherwise.
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393.                                                                         PPPPaaaaggggeeee 6666
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400. XXXXDDDDRRRR((((3333RRRR))))                                                                XXXXDDDDRRRR((((3333RRRR))))
  401.  
  402.  
  403.  
  404.           bool_t
  405.           xdr_vector(XDR *xdrs, char *arrp,
  406.                u_int size, u_int elsize, xdrproc_t elproc)
  407.  
  408.  
  409.           A filter primitive that translates between fixed-length arrays and
  410.           their corresponding external representations.  The parameter _a_r_r_p is
  411.           the address of the pointer to the array, while _s_i_z_e is the element
  412.           count of the array.  The parameter _e_l_s_i_z_e is the _s_i_z_e_o_f each of the
  413.           array's elements, and _e_l_p_r_o_c is an XDR filter that translates
  414.           between the array elements' C form, and their external
  415.           representation.  This routine returns 1 if it succeeds, 0 otherwise.
  416.  
  417.  
  418.           bool_t
  419.           xdr_void(XDR *xdrs, void *v)
  420.  
  421.  
  422.           This routine always returns 1.  It may be passed to RPC routines
  423.           that require a function parameter, where nothing is to be done.
  424.  
  425.  
  426.           bool_t
  427.           xdr_wrapstring(XDR *xdrs, char **sp)
  428.  
  429.  
  430.           A primitive that calls
  431.  
  432.                xdr_string(xdrs, sp, UINT_MAX);
  433.  
  434.           where _U_I_N_T__M_A_X is the maximum value of an unsigned integer, as
  435.           defined in <_l_i_m_i_t_s._h>.  _x_d_r__w_r_a_p_s_t_r_i_n_g() is handy because the RPC
  436.           package passes a maximum of two XDR routines as parameters, and
  437.           _x_d_r__s_t_r_i_n_g(), one of the most frequently used primitives, requires
  438.           three.  Returns 1 if it succeeds, 0 otherwise.
  439.  
  440.  
  441.           void
  442.           xdrmem_create(XDR *xdrs, void *addr,
  443.                u_int size, enum xdr_op op)
  444.  
  445.  
  446.           This routine initializes the XDR stream object pointed to by _x_d_r_s.
  447.           The stream's data is written to, or read from, a chunk of memory at
  448.           location _a_d_d_r whose length is no more than _s_i_z_e bytes long.  The _o_p
  449.           determines the direction of the XDR stream (either XXXXDDDDRRRR____EEEENNNNCCCCOOOODDDDEEEE,
  450.           XXXXDDDDRRRR____DDDDEEEECCCCOOOODDDDEEEE, or XXXXDDDDRRRR____FFFFRRRREEEEEEEE).
  451.  
  452.  
  453.           void
  454.           xdrrec_create(XDR *xdrs, u_int sendsize, u_int recvsize,
  455.                void *handle,
  456.  
  457.  
  458.  
  459.                                                                         PPPPaaaaggggeeee 7777
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466. XXXXDDDDRRRR((((3333RRRR))))                                                                XXXXDDDDRRRR((((3333RRRR))))
  467.  
  468.  
  469.  
  470.               int (*readit)(void *, void *, u_int),
  471.                int (*writeit)(void *, void *, u_int))
  472.  
  473.  
  474.           This routine initializes the XDR stream object pointed to by _x_d_r_s.
  475.           The stream's data is written to a buffer of size _s_e_n_d_s_i_z_e; a value
  476.           of 0 indicates the system should use a suitable default. The
  477.           stream's data is read from a buffer of size _r_e_c_v_s_i_z_e; it too can be
  478.           set to a suitable default by passing a zero value.  When a stream's
  479.           output buffer is full, _w_r_i_t_e_i_t is called.  Similarly, when a
  480.           stream's input buffer is empty, _r_e_a_d_i_t is called.  The behavior of
  481.           these two routines is similar to the system calls _r_e_a_d(2) and
  482.           _w_r_i_t_e(2), except that _h_a_n_d_l_e is passed to the former routines as the
  483.           first parameter.  Note: the XDR stream's _o_p field must be set by the
  484.           caller.
  485.  
  486.           Warning: this XDR stream implements an intermediate record stream.
  487.           Therefore there are additional bytes in the stream to provide record
  488.           boundary information.
  489.  
  490.  
  491.           bool_t
  492.           xdrrec_endofrecord(XDR *xdrs, bool_t sendnow)
  493.  
  494.  
  495.           This routine can be invoked only on streams created by
  496.           _x_d_r_r_e_c__c_r_e_a_t_e().  The data in the output buffer is marked as a
  497.           completed record, and the output buffer is optionally written out if
  498.           _s_e_n_d_n_o_w is non-zero. This routine returns 1 if it succeeds, 0
  499.           otherwise.
  500.  
  501.  
  502.           bool_t
  503.           xdrrec_eof(XDR *xdrs)
  504.  
  505.  
  506.           This routine can be invoked only on streams created by
  507.           _x_d_r_r_e_c__c_r_e_a_t_e().  After consuming the rest of the current record in
  508.           the stream, this routine returns 1 if the stream has no more input,
  509.           0 otherwise.
  510.  
  511.  
  512.           int
  513.           xdrrec_readbytes(XDR *xdrs, caddr_t addr, u_int len)
  514.  
  515.  
  516.           This routine reads data from the stream. It behaves like the _r_e_a_d(2)
  517.           system call against a pipe - it returns up to the number of bytes
  518.           requested and a return of zero indicates end-of-record.  A -1 means
  519.           something very bad happened.
  520.  
  521.  
  522.  
  523.  
  524.  
  525.                                                                         PPPPaaaaggggeeee 8888
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532. XXXXDDDDRRRR((((3333RRRR))))                                                                XXXXDDDDRRRR((((3333RRRR))))
  533.  
  534.  
  535.  
  536.           bool_t
  537.           xdrrec_skiprecord(XDR *xdrs)
  538.  
  539.  
  540.           This routine can be invoked only on streams created by
  541.           _x_d_r_r_e_c__c_r_e_a_t_e().  It tells the XDR implementation that the rest of
  542.           the current record in the stream's input buffer should be discarded.
  543.           This routine returns 1 if it succeeds, 0 otherwise.
  544.  
  545.  
  546.           void
  547.           xdrstdio_create(XDR *xdrs, FILE *file, enum xdr_op op)
  548.  
  549.  
  550.           This routine initializes the XDR stream object pointed to by _x_d_r_s.
  551.           The XDR stream data is written to, or read from, the Standard _I/_O
  552.           stream _f_i_l_e.  The parameter _o_p determines the direction of the XDR
  553.           stream (either XXXXDDDDRRRR____EEEENNNNCCCCOOOODDDDEEEE, XXXXDDDDRRRR____DDDDEEEECCCCOOOODDDDEEEE, or XXXXDDDDRRRR____FFFFRRRREEEEEEEE).
  554.  
  555.           Warning: the destroy routine associated with such XDR streams calls
  556.           _f_f_l_u_s_h(3S) on the _f_i_l_e stream, but never _f_c_l_o_s_e(3S).
  557.  
  558.  
  559. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  560.      rpc(3R), _I_R_I_X _N_e_t_w_o_r_k _P_r_o_g_r_a_m_m_i_n_g _G_u_i_d_e.
  561.  
  562.  
  563.  
  564.  
  565.  
  566.  
  567.  
  568.  
  569.  
  570.  
  571.  
  572.  
  573.  
  574.  
  575.  
  576.  
  577.  
  578.  
  579.  
  580.  
  581.  
  582.  
  583.  
  584.  
  585.  
  586.  
  587.  
  588.  
  589.  
  590.  
  591.                                                                         PPPPaaaaggggeeee 9999
  592.  
  593.  
  594.  
  595.